home *** CD-ROM | disk | FTP | other *** search
/ The Epic Collection 3 / Epic Collection 3, The (1997)(Epic Marketing)[!].iso / system / c / dostrace.doc < prev    next >
Text File  |  1996-09-08  |  18KB  |  704 lines
  1.  
  2.  
  3.                         DOSTrace v2.10 User Manual                   1
  4.  
  5.  
  6.                               DOSTrace v2.10
  7.  
  8.                         Copyright © 1993 Peter Stuer
  9.                             All rights reserved
  10.  
  11.                       Release date November 15, 1993
  12.  
  13.                                  FREEWARE
  14.  
  15.                                 User Manual
  16.  
  17.  
  18.      COPYRIGHT NOTICE 
  19.  
  20.      DOSTrace software and documentation are Copyright © 1993 by Peter
  21.      Stuer. All rights reserved.  
  22.  
  23.  
  24.      DISCLAIMER 
  25.  
  26.      DOSTrace has proven to be stable in everyday use. The author is
  27.      not responsible for any loss of data, damages to software or
  28.      hardware that may result directly or indirectly from the use of
  29.      this program. The author reserves the right to make changes to
  30.      the software or documentation without notice.  
  31.  
  32.  
  33.      PREFACE 
  34.  
  35.      This program is freeware, this means that you can copy it freely
  36.      as long as you don't ask any more money for it than a nominal
  37.      fee for copying. If you want to distribute this program you
  38.      should keep this document with it. This program cannot be used
  39.      for commercial purposes without written permission from the
  40.      author.  
  41.  
  42.      None of the files of the DOSTrace package may be modified or
  43.      left out without permission of the author. Crunching or
  44.      archiving is allowed only if none of the DOSTrace files get
  45.      modified by it.  
  46.  
  47.      Special permission is hereby granted to include DOSTrace in
  48.      Public-Domain collections such as Fred Fish's Amiga Library.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.      
  65.  
  66.  
  67.                         DOSTrace v2.10 User Manual                   2
  68.  
  69.  
  70.      Chapter 1 Introduction      
  71.  
  72.      1.1 What is DOSTrace ?    
  73.  
  74.          DOSTrace is a program that allows you to monitor what
  75.      AmigaDOS is doing while you are working with your Amiga. You can
  76.      watch which files your programs use, if they find all the files
  77.      they require, where they are looking for them and much other
  78.      activity of that kind.  
  79.  
  80.      If this sounds familiar to you, you must be one of the many
  81.      SnoopDos users in the Amiga community. This tool was written to
  82.      replace SnoopDos. It shows you a lot more information than
  83.      SnoopDos and it does this in a verbose way. SnoopDos is written
  84.      by Eddy Carroll and freely distributable.  
  85.  
  86.  
  87.      1.2 Features of DOSTrace     
  88.  
  89.          DOSTrace monitors a lot more AmigaDOS activity than
  90.      SnoopDOS.  Currently the following functions can be monitored: 
  91.  
  92.              AddBuffers      LoadSeg (InternalLoadSeg, NewLoadSeg) 
  93.              Close           Lock 
  94.              CreateDir       MakeLink 
  95.              CurrentDir      Open 
  96.              DeleteFile      ParentDir 
  97.              DeviceProc      Rename 
  98.              ExAll           SetComment 
  99.              Examine         SetOwner 
  100.              ExamineFH       StartNotify 
  101.              Execute         SystemTagList 
  102.              GetDeviceProc   UnLock 
  103.              Info 
  104.  
  105.      You can specify which functions DOSTrace should monitor.  
  106.  
  107.      DOSTrace saves the trace information it gathers as session
  108.      history. It provides a scrollbar which enables you to scroll
  109.      through the session history.  
  110.  
  111.      DOSTrace is also a commodity. You can specify a hotkey to show
  112.      or hide the output window.  
  113.  
  114.      DOSTrace can open on any public screen.  
  115.  
  116.      DOSTrace can trace a single task specified by the user.  
  117.  
  118.  
  119.      1.3 System requirements      
  120.  
  121.          DOSTrace should run on any Amiga system with at least 512K
  122.      RAM and one disk-drive. DOSTrace requires KickStart v2.04 or
  123.      higher to run. Special care has been taken in the program design
  124.      to make the program work with 68020, 68030 and 68040 processors
  125.      without sacrificing 68000 compatibility.  
  126.  
  127.  
  128.      
  129.  
  130.  
  131.                         DOSTrace v2.10 User Manual                   3
  132.  
  133.  
  134.  
  135.      DOSTrace also requires the ReqTools.library v38 or higher.
  136.      ReqTools is copyright © 1992, 1993 by Nico François.  
  137.  
  138.      DOSTrace is KickStart 3.0 compatible and aware. It will show you
  139.      some of the new features available with this version of the
  140.      operating system.  
  141.  
  142.      Should you have any trouble running DOSTrace on your machine,
  143.      please contact me with the full specifications of your machine,
  144.      that is KickStart version, model, expansion boards etc...  
  145.  
  146.  
  147.      1.4 About the author and the program  
  148.  
  149.          DOSTrace has been created using the Macro68 Assembler and
  150.      CygnusEd Professional 3 on an Amiga A3000 25/100 with 10MB
  151.      memory. The DOSTrace documentation was formatted with PRoff.  
  152.  
  153.      If you have suggestions or remarks about this program, or if you
  154.      find any bugs, please let me know.  
  155.  
  156.      When sending in bug reports, please state exactly under what
  157.      circumstances the bug occurred, what equipment was used and what
  158.      happened. If possible also try to give me enough information to
  159.      reproduce the bug. It is very difficult to find bugs when you
  160.      don't know exactly what happened.  
  161.  
  162.      Write to the following address: 
  163.  
  164.              Fido     :  2:292/603.7 (Peter Stuer)
  165.              AmigaNet : 39:120/102.7 (Peter Stuer)
  166.              NLA Net  : 14:200/101.7 (Peter Stuer)
  167.  
  168.              UUCP     : Peter.Stuer@p7.f603.n292.z2.FidoNet.Org
  169.  
  170.              SnailMail: Peter Stuer
  171.                         Beatrijslaan 2 bus 13
  172.                         B-2050 Antwerpen L.O.
  173.                         Belgium - Europe
  174.  
  175.      I will also try to put the latest available version of DOSTrace
  176.      on the following BBS (this may change without further notice): 
  177.  
  178.              Great Balls Of Fire BBS 
  179.              ReqTools Support BBS 
  180.              Herman Stevens 
  181.              Lubbeek 
  182.              ADS Distribution HUB 
  183.              ABC Host Belgium 
  184.              AFN Host Belgium 
  185.              Tel. +32-(0)16-64.09.12 
  186.              ZyXEL U1496+ 16800 BPS (N.8.1) v32bis v42bis 
  187.              24-24 h.  
  188.              Fido Node  2:292/603 
  189.              NLA Node  14:200/101.0 
  190.  
  191.  
  192.      
  193.  
  194.  
  195.                         DOSTrace v2.10 User Manual                   4
  196.  
  197.  
  198.              AmyNet    39:120/102.0 
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.      
  257.  
  258.  
  259.                         DOSTrace v2.10 User Manual                   5
  260.  
  261.  
  262.      Chapter 2 Using DOSTrace     
  263.  
  264.          You can be start DOSTrace from the CLI/Shell or the
  265.      Workbench.  DOSTrace will always check to make sure it is not
  266.      already running.  If so, the copy of DT that is already running
  267.      will be notified and its window will open or come to the front.
  268.      The second copy will exit quietly.  
  269.  
  270.  
  271.      2.1 Starting DOSTrace from the Shell   
  272.  
  273.          To start DOSTrace from the Shell simply type: 
  274.  
  275.              1> DOSTrace 
  276.  
  277.      followed by a return. If you want to continue using the Shell
  278.      while DOSTrace is running, you need to prepend the Run command
  279.      before DOSTrace as follows: 
  280.  
  281.              1> run DOSTrace 
  282.  
  283.      If DOSTrace is succesful in initializing itself, you see the
  284.      DOSTrace window and will start monitoring AmigaDOS. If no window
  285.      is displayed, consult Appendix A (Troubleshooting) for more
  286.      assistance.  
  287.  
  288.  
  289.      2.2 Shell Startup Options     
  290.  
  291.          DOSTrace can be started with various options. If you run
  292.      DOSTrace with a questionmark (?) as argument you'll get the
  293.      argument template.  
  294.  
  295.  
  296.      HISTORY 
  297.  
  298.        This option tells DOSTrace how many lines of history it should
  299.        keep. Use 0 to disable the history feature. The default number
  300.        of history lines is 256.  
  301.  
  302.      OUTPUT 
  303.  
  304.        With this option you can direct the trace information to some
  305.        other AmigaDOS device of file in addition or in place of the
  306.        information being displayed in the window.  
  307.  
  308.        If you have a debugging terminal attached to the serial port
  309.        you could use 'DOSTrace OUTPUT=AUX:' to have all trace
  310.        information appear at the terminal.  
  311.  
  312.        A special symbol is DEBUG. 'OUTPUT=DEBUG' will output all
  313.        trace information to the serial port at 9600 baud.  
  314.  
  315.      WIDTH 
  316.  
  317.        This option specifies the width of the DOSTrace output window
  318.  
  319.  
  320.      
  321.  
  322.  
  323.                         DOSTrace v2.10 User Manual                   6
  324.  
  325.  
  326.        in pixels. By default, DOSTrace will open a window that is as
  327.        wide as the visible width of the public screen it is appearing
  328.        on.  
  329.  
  330.      HEIGHT 
  331.  
  332.        This option specifies the height of the DOSTrace output window
  333.        in screen lines. By default, DOSTrace will open a window that
  334.        is as high as the visible height of the public screen it is
  335.        appearing on, without overlapping the title bar.  
  336.  
  337.      SCREEN 
  338.  
  339.        If you do not use this option, DOSTrace will open on the
  340.        default public screen which is most of the times the Workbench
  341.        screen.  DOSTrace will try to open on the public screen whose
  342.        name is specified after this argument.  
  343.  
  344.      TRACEMASK 
  345.  
  346.        By specifying a trace mask you can determine which AmigaDOS
  347.        functions DOSTrace will actually trace. The trace mask
  348.        consists of a string of characters. The function corresponding
  349.        to the character will be traced. Use the following characters: 
  350.  
  351.              A: AddBuffers      M: LoadSeg 
  352.              B: CreateDir       N: Lock 
  353.              C: CurrentDir      O: MakeLink 
  354.              D: DeleteFile      P: NewLoadSeg 
  355.              E: DeviceProc      Q: Open 
  356.              F: ExAll           R: ParentDir 
  357.              G: Examine         S: Rename 
  358.              H: ExamineFH       T: SetComment 
  359.              I: Execute         U: SetOwner 
  360.              J: GetDeviceProc   V: StartNotify 
  361.              K: Info            W: SystemTagList 
  362.              L: InternalLoadSeg X: Close 
  363.                                 Y: UnLock 
  364.  
  365.        For example, TRACEMASK=CDMNQI will only trace the AmigaDOS
  366.        functions that SnoopDOS 1.7 traces. By default, DOSTrace
  367.        monitors all AmigaDOS functions it knows about.  
  368.  
  369.      TASK 
  370.  
  371.        If you want to trace the dos operations of a particular task,
  372.        this option will allow you to specify the address of that
  373.        task.  For example, DT TASK=$0786ecc8 will only show the
  374.        activity of the program that has its Task/Process structure at
  375.        address $0786ECC8.  The dollar sign ($) is optional and the
  376.        number is case-insensitive.  
  377.  
  378.        When DOSTrace is already running, you can use the "Task"
  379.        menuitem of the "Project" menu. This will pop up a requester
  380.        that asks you to enter the address of the Task/Process
  381.        structure of the program you want to trace. If you enter an
  382.  
  383.  
  384.      
  385.  
  386.  
  387.                         DOSTrace v2.10 User Manual                   7
  388.  
  389.  
  390.        address that does not point to a Task structure, DOSTrace will
  391.        beep the display.  
  392.  
  393.        The name of the task currently being traced will be shown in
  394.        the title bar of the DOSTrace window.  
  395.  
  396.        To stop tracing a particular task, select the "Task" menuitem
  397.        of the "Project" menu and clear the address shown there. If
  398.        you then select "Ok", the title bar will reset and DOSTrace
  399.        will continue to trace all tasks.  
  400.  
  401.      CX_PRIORITY 
  402.  
  403.        This option allows you to specify priority relative to the
  404.        other Commodities programs. Default priority is 0.  
  405.  
  406.      CX_POPKEY 
  407.  
  408.        This option allows you to change the default hot key for
  409.        DOSTrace.  The default hot key is 'ralt d' (right Alt key
  410.        pressed with 'd').  
  411.  
  412.      CX_POPUP 
  413.  
  414.        If you do not want DOSTrace to open its window, you can
  415.        specify the CX_POPUP switch like this: DT CX_POPUP=NO. By
  416.        default, the DOSTrace window will open.  
  417.  
  418.      CX_ACTIVE 
  419.  
  420.        By specifying CX_ACTIVE=NO, DOSTrace start without its tracing
  421.        code enabled. By default, tracing starts immediately.  
  422.  
  423.  
  424.      2.3 Starting DOSTrace from the Workbench   
  425.  
  426.          To start DOSTrace from the Workbench, simply double-click on
  427.      the DOSTrace icon to start the program or use the 'Execute
  428.      Command' item from the 'Workbench' menu.  
  429.  
  430.  
  431.      2.4 Workbench Startup Options     
  432.  
  433.          You can specify the same options as explained in the
  434.      paragraph "Shell Startup Options" by adding tooltypes to the
  435.      DOSTrace icon.  
  436.  
  437.                                    NOTE
  438.  
  439.           If you use the CX_POPUP and/or the CX_ACTIVE tooltype
  440.           you must specify them with '=YES' appended to them.
  441.           For example, 'CX_POPUP=YES'. Not using them defaults
  442.           to CX_POPUP=YES and CX_ACTIVE=YES.  
  443.  
  444.  
  445.  
  446.  
  447.      
  448.  
  449.  
  450.                         DOSTrace v2.10 User Manual                   8
  451.  
  452.  
  453.      To change the task priority of DOSTrace you can add the TOOLPRI
  454.      tooltype to the DOSTrace icon. For example, adding TOOLPRI=5 will
  455.      start running DOSTrace with task priority 5.
  456.  
  457.  
  458.      2.5 Stopping DOSTrace     
  459.  
  460.          You can stop DOSTrace at any time by sending it a break signal. If
  461.      you started DOSTrace from the Shell, you can do this by pressing
  462.      Ctrl-C.
  463.  
  464.      Since DOSTrace is a commodity you can use the Exchange utility to
  465.      control it.
  466.  
  467.        'Show Interface' will open the DOSTrace output window
  468.  
  469.        'Hide Interface' will close the DOSTrace output window
  470.  
  471.        The 'Active/Inactive' cycle gadget will toggle DOSTrace's
  472.        activation status. When DOSTrace is active it will update it's
  473.        internal history even when the output window is closed; when it is
  474.        inactive, no tracing will occur.
  475.  
  476.        The "Active" menuitem of the "Project" menu will also allow you to
  477.        toggle the activation status of DOSTrace.
  478.  
  479.        'Remove' will tell DOSTrace to quit.
  480.  
  481.      The 'Quit' menu item will exit DOSTrace.
  482.  
  483.                                    NOTE
  484.  
  485.           DOSTrace will try to quit immediately. If any of the
  486.           patches are still in use, it will wait until no
  487.           program uses the DOSTrace patches anymore.  
  488.  
  489.  
  490.  
  491.      2.6 About the trace output   
  492.  
  493.          The information shown depends on which function is being traced
  494.      but all messages have 3 components in common:
  495.  
  496.              Process Name    The name of the process calling the
  497.                              AmigaDOS function.
  498.  
  499.              Trace Info      Verbose information about the function
  500.                              being executed.
  501.  
  502.              Result          Whether the call was succesfull or not
  503.                              (if applicable)
  504.  
  505.      :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  506.      ::::::::::::::::::::::: DOSTRACE HISTORY ::::::::::::::::::::::::
  507.      :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  508.  
  509.  
  510.      
  511.  
  512.  
  513.                         DOSTrace v2.10 User Manual                   9
  514.  
  515.  
  516.  
  517.      ::: Version 2.10 ::: November 15, 1993 ::::::::::::::::::::::::::
  518.  
  519.      - NEW: Added trace code for Close and UnLock.
  520.  
  521.      - NEW: Removed the annoying delay when quitting DOSTrace. Thanks
  522.        to Rafael D'Halleweyn for the suggestion.
  523.  
  524.      - NEW: Added up/down gadgets to scroll up/down line by line.
  525.  
  526.      - NEW: Added the TASK option and Task menu item (requested by
  527.        Jan Dujardin)
  528.  
  529.      - NEW: Added Clear menu item to clear the history buffer while
  530.        DOSTrace is running.
  531.  
  532.      - NEW: Added an Active menu item to make activating and
  533.        deactivating DOSTrace on the fly easier.
  534.  
  535.      - IMPROVED: Optimized some of the core routines.
  536.  
  537.      - IMPROVED: DOSTrace starts active and with the output window
  538.        open when run from the CLI.
  539.  
  540.      - IMPROVED: Removed inner border to make DOSTrace more conform to
  541.        the Style Guide.
  542.  
  543.      - IMPROVED: Execute() and SystemTagList() now show which program
  544.        they are trying to run before the program starts running.
  545.  
  546.      - IMPROVED: When DOSTrace is unable to determine the filename of
  547.        the object a DOS function is acting on it will use the name
  548.        "Unknown Object" instead.
  549.  
  550.        You will notice this especially when closing or unlocking
  551.        objects that do not or incompletely support a file system like
  552.        CON:, PRT: or NIL:.
  553.  
  554.      - BUG FIX: Removed a bug that caused a signal to stay allocated.
  555.  
  556.      - BUG FIX: Fixed a display bug.
  557.  
  558.      ::: Version 2.00 ::: August 21, 1993 ::::::::::::::::::::::::::::
  559.  
  560.      - Complete rewrite.
  561.  
  562.      - NEW: Added monitoring code for InternalLoadSeg and NewLoadSeg.
  563.  
  564.      - IMPROVED: Made trace code smaller and faster.
  565.  
  566.      - BUG FIX: Suppressing Workbench's background DOS operations did
  567.        not work always.
  568.  
  569.      - BUG FIX: I forgot (again) that some programs still wrongly
  570.        expect that D0 and D1 are equal when returning from LoadSeg.
  571.        This should fix problems with programs that use old overlay
  572.  
  573.  
  574.      
  575.  
  576.  
  577.                         DOSTrace v2.10 User Manual                  10
  578.  
  579.  
  580.        managers.
  581.  
  582.      ::: Version 1.00 ::: June 22, 1993 ::::::::::::::::::::::::::::::
  583.  
  584.      - First release
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.      
  639.  
  640.  
  641.      
  642.  
  643.  
  644.                              Table Of Contents
  645.  
  646.                               DOSTrace v2.10
  647.  
  648.      Chapter 1 Introduction     ................................    2
  649.         1.1 What is DOSTrace ?   ...............................    2
  650.         1.2 Features of DOSTrace    ............................    2
  651.         1.3 System requirements     ............................    2
  652.         1.4 About the author and the program ...................    3
  653.      Chapter 2 Using DOSTrace    ...............................    5
  654.         2.1 Starting DOSTrace from the Shell  ..................    5
  655.         2.2 Shell Startup Options    ...........................    5
  656.         2.3 Starting DOSTrace from the Workbench  ..............    7
  657.         2.4 Workbench Startup Options    .......................    7
  658.         2.5 Stopping DOSTrace     ..............................    8
  659.         2.6 About the trace output   ...........................    8
  660.  
  661.      Copyright © 1993 DOSTrace v2.10 written by Peter Stuer
  662.  
  663.  
  664.      Thanks to Nico François, Johan van Houtven, Hermans Stevens, Jan
  665.      Dujardin, Rafael D'Halleweyn, Stu Churchill, Magnus Holmgren and
  666.      Per-Anders Josefsson for testing DOSTrace.
  667.                   _
  668.                _ //
  669.      Thanks to \X/ Amiga for being the best computer ever !
  670.  
  671.  
  672.  
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.  
  702.      
  703.  
  704.